home *** CD-ROM | disk | FTP | other *** search
/ Super PC 34 / Super PC 34 (Shareware).iso / spc / UTIL / DJGPP2 / CONTRIB / MAN_PC.ZIP / man_pc / man / README < prev   
Encoding:
Text File  |  1995-06-20  |  4.9 KB  |  125 lines
  1. man v3.0.2 92/10/11
  2. -------------------
  3.  
  4. This is a man(1) program, to be used in conjunction with manpager (which
  5. I concurrently posted). It is fairly robust, patterned after BSD unix man.
  6. It requires ul(1) and cat(1), if the "-" and "-ul" options are used,
  7. whatis(1) if the "-f" option is used, apropos(1) for the "-k" option, and
  8. always needs either less (setenv PAGER c:\bin\less.ttp) or manpager
  9. (setenv MANPAGER c:\bin\manpager.ttp). One of these is required, or you
  10. can setenv PAGER to your own prefered pager. Personally, I think less
  11. is superior over pg or more. And this version is really oriented toward
  12. using manpager, for reading nroff v1.10p4 manpages (with font changes).
  13.  
  14. NOTE: the manpage posted here, "man.1", uses special escape sequences
  15. for changing fonts, so it must be viewed with manpager to get the full
  16. effect. You can also use less or emacs, in a pinch.
  17.  
  18. What is nice about this man, is that it can deal with files compressed
  19. with compress(1), using the "-z" switch in manpager (less does not support
  20. this directly) without resorting to something like "zcat file | less".
  21. I tested man and manpager with the compress on atari.archive.umich.edu
  22. (terminator) which is v4.3, 16-bit. For more on this, see manpager docs.
  23.  
  24. Incidently, when I say "man(1)", the "(1)" refers to the section of the
  25. unix programmer's manual (more on this below). Section 1 is user commands.
  26. It is just the way things are refered to in unix-land.
  27.  
  28. I was going to post apropos(1), whatis(1), and whatisin(1), but they need
  29. more work before I do. No timeframe for this. Sorry.
  30.  
  31. Anyway, it is pretty simple to use. To set up a manpage directory, do this:
  32.  
  33.     1) mkdir c:\man (this is the root of the manpage tree, the default
  34.        in the program, too, but you can use anything you like).
  35.  
  36.     2) cd c:\man
  37.        mkdir man0 man1 man2 man3 man4 man5 man6 man7 man8
  38.        mkdir manl mano mann. You will place formatted manpages in this
  39.        tree (those already run through nroff). Normally, these would be
  40.        called "catpages" and placed in .\cat*. man does NOT invoke nroff!
  41.  
  42.     3) copy man.ttp to your bin directory and rehash your shell. man can
  43.        also be run from the desktop, but you need an environment if you
  44.        want to override the default man directory.
  45.  
  46.     4) setenv MANDIR c:\man (or whatever).
  47.  
  48.     5) setenv MANPAGER c:\bin\manpager.ttp.
  49.  
  50.     6) put some manpages in the c:\man\man* directories as follows (note
  51.        that file extensions ARE important and MUST correspond to the
  52.        last char of the subdirectory):
  53.  
  54.         subdir    filename    description
  55.  
  56.         man0    *.0        general information
  57.         man1    *.1        commands
  58.         man2    *.2?        system calls, my convention is
  59.                     *.2    normal unix system calls
  60.                     *.2g    gemdos
  61.                     *.2b    bios
  62.                     *.2x    xbios
  63.         man3    *.3?        libraries, normal unix convention is
  64.                     *.3    general libc
  65.                     *.3s    stdio (fopen, etc)
  66.                     *.3m    math (sin, etc)
  67.                     *.3c    compatibility
  68.                     *.3x    others
  69.         man4    *.4        devices, special files (for dev drivers
  70.                     on unix, i use it for things like
  71.                     sound.4, dma.4, etc)
  72.         man5    *.5        file formats (e.g. arc.5, ar.5, tar.5)
  73.         man6    *.6        games
  74.         man7    *.7        misc
  75.         man8    *.8        system administration (e.g. ramdisk.8)
  76.         manl    *.l        local commands specific to your setup
  77.         mano    *.o        old manpages (replaced with newer)
  78.         mann    *.n        new manpages (for testing prior to
  79.                     install)
  80.  
  81.        You can start with man's manpage (cp man.1 c:\man\man1).
  82.  
  83.     7) run man (man man) if you copied man.1 to c:\man\man1. You do not
  84.        specify the section in the file name. note that
  85.        if you have 2 manpages called "xyz" (i.e. xyz.1 and xyz.2), man
  86.        will ALWAYS find xyz.1 and never the other. if you want xyz.2,
  87.        you should specify the section as in "man 2 xyz".
  88.  
  89.     8) if you want to use the -k and -f options, you will have to build
  90.        a whatis(1) database, which is simply the NAME text from manpages,
  91.        one per single line. the whatis entry for man is:
  92.  
  93.        man - read online documentation
  94.  
  95.        "whatis" is a file which goes in c:\lib. a sample is included
  96.        here. Each time you add a manpage to the system, add the NAME line
  97.        to whatis in the format specified (see whatis file). my own file
  98.        has about 600 entries!
  99.  
  100. You don't have to stick with these (BSD) conventions, but it will make life
  101. simpler. At any rate, the program requires the directory stucture and searches
  102. there. See the manpage (or source) for the search order. Try to put only
  103. unix commands in man1 (putting other commands like uniterm) in manl. I have
  104. hundreds of files in man1, and it gets to be a pain after a while.
  105.  
  106. Note that it is not necessarily to have a manpage for 2 commands or functions
  107. which share the same manpage. You can "source" a manpage from another by
  108. placing a single line in the file with a line such as:
  109.  
  110.     .so man3\fclose.3s
  111.  
  112. This is the manpage for fflush(3S). It uses the manpage for fclose(3S).
  113.  
  114. Someday, I may post manpages for sections 2 (bios, xbios, gemdos) and possibly
  115. section 3 (dlibs, gemlib, etc). Don't hold your breath, though :-).
  116.  
  117.  
  118. Enjoy...
  119.  
  120.  
  121. -Bill Rosenkranz
  122. rosenkra@convex.com
  123.  
  124.  
  125.